# @tarko/agent

## Introduction

`@tarko/agent` is an event-stream driven meta agent framework for building effective multimodal Agents.

## When to use?

This Agent SDK provides a low-level programmatic API, useful when you want to build an AI agent from scratch, e.g.

- **MCP Agent**: Connect to mcp client (official implementation: [@tarko/mcp-agent](../mcp-agent/core.md))
- **GUI Agent**: Build a gui agent (official implementation: [@gui-agent/core](../gui-agent/core.md))

## Install

```bash
npm install @tarko/agent
```

## Features

- [x] **Tool Integration**: Effortlessly create and call tools within agent responses.
- [x] **Event-stream driven**: Standard Event Stream protocol driver to build Context and UI more efficiently.
- [x] **Native Streaming**: Native streaming allows you to understand the Agent's output in real time.
- [x] **Multimodal analysis**: Automatically analysis multimodal tool result allowing you to focus more on building Agents.
- [x] **Strong extension capabilities**: Rich lifecycle design allows you to implement more high-level Agents.
- [x] **Mutiple model providers**: Supports multiple models, and supports advance configuration and runtime selection.
- [x] **Mutiple tool call engines**: The multiple tool call engine allows you to more easily access tool calling capabilities

## Quick Start

Create a `index.ts`:

```ts
import { Agent, Tool, z } from '@tarko/agent';

const locationTool = new Tool({
  id: 'getCurrentLocation',
  description: "Get user's current location",
  parameters: z.object({}),
  function: async () => {
    return { location: 'Boston' };
  },
});

const weatherTool = new Tool({
  id: 'getWeather',
  description: 'Get weather information for a specified location',
  parameters: z.object({
    location: z.string().describe('Location name, such as city name'),
  }),
  function: async (input) => {
    const { location } = input;
    return {
      location,
      temperature: '70°F (21°C)',
      condition: 'Sunny',
      precipitation: '10%',
      humidity: '45%',
      wind: '5 mph',
    };
  },
});

const agent = new Agent({
  tools: [locationTool, weatherTool],
});

async function main() {
  const response = await agent.run({
    input: "How's the weather today?",
  });
  console.log(response);
}

main();
```

Execute it:

```bash
npx tsx index.ts
```

Output:

```json
{
  "id": "5c38c0a1-ccbe-48f0-8b97-ae78a4d9407e",
  "type": "assistant_message",
  "timestamp": 1750188571248,
  "content": "The weather in Boston today is sunny with a temperature of 70°F (21°C). There's a 10% chance of precipitation, humidity is at 45%, and the wind is blowing at 5 mph.",
  "finishReason": "stop",
  "messageId": "msg_1750188570877_ics24k3x"
}
```

## API

### Agent

Define a `Agent` instance:

```ts
const agent = new Agent({
  /* AgentOptions */
});
```

All agent options please refer to [Agent Config](../../api/config/agent.md).

### Tool

Define a `Tool` instance:

```ts
import { Tool, z } from '@tarko/agent';

const locationTool = new Tool({
  id: 'getCurrentLocation',
  description: "Get user's current location",
  parameters: z.object({}),
  function: async () => {
    return { location: 'Boston' };
  },
});
```

## Guide

### Streaming Mode

In above basic example, if you enable `stream: true`:

```ts
async function main() {
  const stream = await agent.run({
    input: "How's the weather today?",
    stream: true,
  });

  for await (const chunk of stream) {
    console.log(JSON.stringify(chunk));
  }
}
```

You will get following outputs:

```jsonl
{"id":"b61e0b7b-1ab0-4507-acd6-a6ba04de7e19","type":"assistant_message","timestamp":1750188853755,"content":"","toolCalls":[{"id":"call_v7VGHOkHf5kDpftNKP46neuv","type":"function","function":{"name":"getCurrentLocation","arguments":"{}"}}],"finishReason":"tool_calls","messageId":"msg_1750188853746_cnb5urei"}
{"id":"89876ba2-33f5-4623-9949-84bab8b5b63c","type":"tool_call","timestamp":1750188853756,"toolCallId":"call_v7VGHOkHf5kDpftNKP46neuv","name":"getCurrentLocation","arguments":{},"startTime":1750188853756,"tool":{"name":"getCurrentLocation","description":"Get user's current location","schema":{"type":"object","properties":{}}}}
{"id":"539e0378-47a9-4585-b27f-dc94007ff8d5","type":"tool_result","timestamp":1750188853757,"toolCallId":"call_v7VGHOkHf5kDpftNKP46neuv","name":"getCurrentLocation","content":{"location":"Boston"},"elapsedMs":1}
{"id":"4e22c5a2-7520-4e60-99a0-388db0e8ed13","type":"assistant_message","timestamp":1750188854919,"content":"","toolCalls":[{"id":"call_lF1zR8bN3uF0uHK1MmWGvCAk","type":"function","function":{"name":"getWeather","arguments":"{\"location\":\"Boston\"}"}}],"finishReason":"tool_calls","messageId":"msg_1750188854825_sj6xqhs4"}
{"id":"484f733f-d8c7-49db-a1e3-0f8312b726a0","type":"tool_call","timestamp":1750188854920,"toolCallId":"call_lF1zR8bN3uF0uHK1MmWGvCAk","name":"getWeather","arguments":{"location":"Boston"},"startTime":1750188854919,"tool":{"name":"getWeather","description":"Get weather information for a specified location","schema":{"type":"object","properties":{"location":{"type":"string","description":"Location name, such as city name"}},"required":["location"]}}}
{"id":"373f04fe-dd00-4c1d-a394-be6ff7f24d51","type":"tool_result","timestamp":1750188854920,"toolCallId":"call_lF1zR8bN3uF0uHK1MmWGvCAk","name":"getWeather","content":{"location":"Boston","temperature":"70°F (21°C)","condition":"Sunny","precipitation":"10%","humidity":"45%","wind":"5 mph"},"elapsedMs":0}
{"id":"ebde4cf4-ad2a-41b4-962f-bb8c1522c487","type":"assistant_streaming_message","timestamp":1750188855408,"content":"The","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"861394e1-0875-4021-b885-17217af0f5af","type":"assistant_streaming_message","timestamp":1750188855409,"content":" weather","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"36650b2b-d50e-48f2-b422-0941eafcd780","type":"assistant_streaming_message","timestamp":1750188855427,"content":" in","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"5144f898-6ea4-46c7-a600-0893faa6f3ac","type":"assistant_streaming_message","timestamp":1750188855434,"content":" Boston","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"05d74613-b3db-4561-8849-741ee29cc432","type":"assistant_streaming_message","timestamp":1750188855436,"content":" today","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"689f1af1-eefc-4f5a-b812-2685d86ece99","type":"assistant_streaming_message","timestamp":1750188855437,"content":" is","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"28492ac5-8317-48a2-ab22-f6551e2df333","type":"assistant_streaming_message","timestamp":1750188855446,"content":" sunny","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"7c4dd396-a0a3-4640-b600-d20bf794a844","type":"assistant_streaming_message","timestamp":1750188855446,"content":" with","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"8ee2d94d-7433-414d-a377-8cf28137c891","type":"assistant_streaming_message","timestamp":1750188855446,"content":" a","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"ef645b8d-d5f7-4f6f-9f18-bd330291f7e0","type":"assistant_streaming_message","timestamp":1750188855446,"content":" temperature","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"e9188def-66de-4a5b-b1cd-6de63fed45a4","type":"assistant_streaming_message","timestamp":1750188855450,"content":" of","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"f65d091e-6a11-4a39-92e3-1eab0d5e8299","type":"assistant_streaming_message","timestamp":1750188855450,"content":" ","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"07b1b39e-6ff3-409c-9454-7b7395bc0117","type":"assistant_streaming_message","timestamp":1750188855464,"content":"70","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"10c828e3-71fe-479f-a5f8-cbe5b6db07ad","type":"assistant_streaming_message","timestamp":1750188855464,"content":"°F","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"bbc7ce06-08d5-470b-b70f-1b57fb84d6bf","type":"assistant_streaming_message","timestamp":1750188855465,"content":" (","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"8739fc0e-b719-41ae-8634-dd3789554c5e","type":"assistant_streaming_message","timestamp":1750188855465,"content":"21","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"727785a3-568a-4d12-afb1-e8f4aa06fa49","type":"assistant_streaming_message","timestamp":1750188855591,"content":"°C","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"3475a90c-edbc-4bb8-bff1-c661986cfe8a","type":"assistant_streaming_message","timestamp":1750188855591,"content":").","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"268f84af-06b8-4af7-bc01-e4a5339c8da9","type":"assistant_streaming_message","timestamp":1750188855592,"content":" The","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"2a2669f8-9c4b-40b5-bf53-6f101e4bc36a","type":"assistant_streaming_message","timestamp":1750188855592,"content":" precipitation","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"91378e16-cd98-4ab1-9af0-219a91782d3d","type":"assistant_streaming_message","timestamp":1750188855593,"content":" chance","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"1bef746f-3c03-42e0-9644-466189c9d77b","type":"assistant_streaming_message","timestamp":1750188855593,"content":" is","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"abbec5f7-0861-4022-b2a6-11700ff204df","type":"assistant_streaming_message","timestamp":1750188855593,"content":" ","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"7d0a76e8-4240-42a5-8b8d-ff9cb70fc873","type":"assistant_streaming_message","timestamp":1750188855593,"content":"10","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"9d8ce867-1f0a-48db-b27b-8dc8e297a8f0","type":"assistant_streaming_message","timestamp":1750188855608,"content":"%,","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"fde17249-6176-4f91-aa97-c16f4cf40a53","type":"assistant_streaming_message","timestamp":1750188855609,"content":" humidity","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"f7313032-0b96-47aa-868b-a863fc9d5fe1","type":"assistant_streaming_message","timestamp":1750188855609,"content":" is","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"b35ff3d2-415b-4013-95c8-b48a24e9e06d","type":"assistant_streaming_message","timestamp":1750188855610,"content":" at","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"56a0f2e7-4b2c-458b-b777-a71799779bec","type":"assistant_streaming_message","timestamp":1750188855627,"content":" ","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"e42610f2-beaa-48f2-b9dc-c20b3933f194","type":"assistant_streaming_message","timestamp":1750188855627,"content":"45","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"fdebd997-8f16-4651-83af-203baf96f898","type":"assistant_streaming_message","timestamp":1750188855688,"content":"%,","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"f76891a3-eecb-48e3-bd4e-71d04c887ffd","type":"assistant_streaming_message","timestamp":1750188855689,"content":" and","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"22abccd6-219b-41d1-b3d8-bc706b089a71","type":"assistant_streaming_message","timestamp":1750188855730,"content":" there's","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"8f0e7cf2-27d3-4cb2-a097-b58a4f413735","type":"assistant_streaming_message","timestamp":1750188855731,"content":" a","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"93897d8c-798a-44c6-948a-0412b032ff9b","type":"assistant_streaming_message","timestamp":1750188855773,"content":" gentle","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"efa05703-df06-471d-954f-01b8a26fa872","type":"assistant_streaming_message","timestamp":1750188855773,"content":" wind","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"20fafc10-7c65-4e89-8ae0-eb88b4604e7c","type":"assistant_streaming_message","timestamp":1750188855792,"content":" blowing","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"467f0099-5b26-46ab-9aa1-d9890edf1b18","type":"assistant_streaming_message","timestamp":1750188855792,"content":" at","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"88075562-34f5-435e-a16e-add2a39eb94f","type":"assistant_streaming_message","timestamp":1750188855794,"content":" ","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"60afb670-4bcc-446a-8dd7-7493fe9f18db","type":"assistant_streaming_message","timestamp":1750188855794,"content":"5","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"53456ed4-ab48-4b31-baf6-81fcc0f02d90","type":"assistant_streaming_message","timestamp":1750188855857,"content":" mph","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"32ae7cda-fc17-4ebf-b919-9efe38db3f2e","type":"assistant_streaming_message","timestamp":1750188855857,"content":".","isComplete":false,"messageId":"msg_1750188855395_phxytayw"}
{"id":"85d06697-25b7-4c85-a04f-f8df550ccef1","type":"assistant_message","timestamp":1750188855867,"content":"The weather in Boston today is sunny with a temperature of 70°F (21°C). The precipitation chance is 10%, humidity is at 45%, and there's a gentle wind blowing at 5 mph.","finishReason":"stop","messageId":"msg_1750188855395_phxytayw"}
```
